home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / prog_c / lsdoor09.zip / EXAMPLE4.H < prev    next >
C/C++ Source or Header  |  1996-06-02  |  8KB  |  159 lines
  1. // Example4.h - Demonstrates use of LsDoor SDK's databases.
  2.  
  3. #ifndef __Example4_HEADER_FILE__   // Using these can be a good habit.
  4. #define __Example4_HEADER_FILE__   // And prevents multiple-inclusion.
  5.  
  6. struct playerType {
  7.   unsigned long num;               // Needed to work the database
  8.   unsigned char bbshandle[20];     // Matches with user.handle
  9.   unsigned char handle[20];        // Asked, not the same as user.handle
  10.   unsigned short points;           // Game stuff, not used in this example
  11.   unsigned short power;            // Game stuff, not used in this example
  12. } player;
  13.  
  14.  
  15.   // Indexing modes:     (Future versions of lsDoor may add more)
  16.   //   (0)  Single Record - Do not use TData for this, see below...
  17.   //   (1)  Standard Database - Uses Indexes and full database support...
  18.   //   (2)  Independant - A complete database with no indexes...
  19.  
  20.   // Single Record:
  21.   //   The easiest kind of data to work with is single record.  You needn't
  22.   // create any TData objects for single record data files.  All you need to
  23.   // do is setup a couple of macros like these:
  24.  
  25. /*
  26. #define load_cfg() read_single("Example5.Cfg"), &cfg, sizeof(cfg), false )
  27. #define save_cfg() write_single("Example5.Cfg"), &cfg, sizeof(cfg) )
  28. */
  29.  
  30.   // Standard Database:
  31.  
  32.   // The C++ Class TData is the heart of all the databases except
  33.   // single-record.  The first step is to create an object of TData (in
  34.   // this case we named it Player) using the file name, size of our data,
  35.   // and the indexing mode we want.
  36.  
  37.   // TData::TData( char *filename, ushort datasize, uchar indexingMode );
  38.  
  39. #ifdef MainModule
  40. TData Player( "Player.Dat", sizeof(player), 1 );
  41. #else
  42. extern TData Player;
  43. #endif
  44.  
  45.   // The following macros are setup for use with an Indexed database.  The
  46.   // key being used is 'player.bbshandle'.  To use a Independant database,
  47.   // change the Indexing Mode above and then replace all occurances of
  48.   // 'player.bbshandle' below with NULL.
  49.  
  50.   // You can have any number of databases, and any number of databases in
  51.   // use at one time.  You don't have to create macros for them all, but
  52.   // we think it will probably speed things up.
  53.  
  54. #define open_player()       Player.Open()
  55.   // Opens the database.  Calls to this function may be nested as many times
  56.   // as needed (i.e. you can call the function 10 times provided you also
  57.   // call the close_player() function an equal number of times.)  No matter
  58.   // what, the actual files will never be opened more than once.  Note that
  59.   // this function has the side-effect of a reset_player() call, which
  60.   // close_player() will NOT undo.  See below regarding reset_player().
  61.  
  62. #define next_player()       Player.Load( (void *)&player )
  63.   // This loads the next record in the database.  Note that the order of
  64.   // records is somewhat random.  This is the easiest and fastest way to
  65.   // load data from a database except when using keys.  This function
  66.   // will return false when it reaches the end of the database, otherwise
  67.   // it will return true and fill the 'player' structure.
  68.  
  69. #define reset_player()      Player.Reset()
  70.   // This restarts the next_player() position to the beginning of
  71.   // the database.  Open_player() also causes a call to this function.
  72.  
  73. #define save_player()       Player.Save( player.bbshandle, player.num, (void *)&player )
  74.   // This function saves the 'player' data to disk.  If the player.num is
  75.   // already in use, the old record of the same number will be overwritten.
  76.   // This allows you to modify a 'player' (modify anything except the
  77.   // player.num) and replace your older data.  If the player.num does not
  78.   // exist, the new record is added.  This function will also create (but
  79.   // not modify) a key using (in this case) player.bbshandle ONLY if the
  80.   // player.num does not already exist.
  81.  
  82. #define add_player()        player.num = Player.GetHigh(); \
  83.                             Player.Add( player.bbshandle, player.num, (void *)&player )
  84.   // This macro will save the current 'player' data to disk, and also assign
  85.   // new player.num to the 'player' structure.  This is much faster than
  86.   // save_player() but cannot overwrite previous data.  If indexing is
  87.   // in use, this function will also create the new key, in this case, using
  88.   // player.bbshandle.
  89.  
  90. #define delete_player()     Player.Delete( player.num, player.bbshandle )
  91.   // To delete a record, load it into 'player', then call this function.
  92.   // This erases a 'player' record on disk and the key that goes with it.
  93.  
  94. #define load_player(NUM)    Player.Load( NUM, (void *)&player )
  95.   // This loads the player by their number.  Every record must have a
  96.   // unique ID given by add_player().  This function returns false if the
  97.   // player could not be found or on error.  This function is fairly slow.
  98.  
  99. #define end_player()        Player.end
  100.   // This function will tell you if NUM of the last load_player() call
  101.   // was past the end of the database.
  102.  
  103. #define close_player()      Player.Close()
  104.   // Call to close an open database.  Calls to Open and Close may be nested
  105.   // but require an equal number of calls to Open as to Close.  See also
  106.   // open_player() above.
  107.  
  108.  
  109.   ///////  Key related...
  110.  
  111.   // These functions let you load data using Indexes, a very fast method.
  112.   // You must decide on what the key's will be, in this case we are using
  113.   // the player's BBS handle (player.bbshandle) for the keys.
  114.  
  115. #define find_player(W)      Player.Load( (unsigned char *)W, (void *)&player )
  116.   // This function uses the char string W to find a matching key.  The
  117.   // search is not case sensitive.  If the key was found, the function
  118.   // fills the 'player' structure with the matching record and returns true.
  119.  
  120. #define change_player(Old,New)  Player.Change( player.num, Old, New )
  121.   // This function MODIFIES a key.  This does not CREATE a key.  The keys
  122.   // are created by the save_player() and add_player() functions.
  123.   // Old and New are both char strings.  You should load the 'player' data
  124.   // being changed before calling.  An example where this might be used
  125.   // would be if the user changed their handle on the BBS.  To be able to
  126.   // find the key ever again you have to change it to match the new
  127.   // user.handle.
  128.  
  129.   ///////  Rarely used and Obsolete functions...
  130.  
  131. #define version_player()    Player.CheckVersion()
  132.   // This function most likely won't be needed by you.  It does not give the
  133.   // version number of the database, but rather it gives the version of
  134.   // TData which it is using.
  135.  
  136. #define isopen_player()     Player.isopen
  137.   // Obsolete, but available.  Simply returns true/false whether the file
  138.   // is open or not.
  139.  
  140. #define high_player()       Player.GetHigh()
  141.   // This function gives the highest player.num currently in use.  Note that
  142.   // this does not indicate how many records are in the database, but rather
  143.   // it indicates how many records have been added since the database was
  144.   // first created.
  145.  
  146. #define key_player()        Player.LoadKey()
  147.   // This function is almost nothing but trouble.  It serves the purpose of
  148.   // returning the next key in the indexes so that you can compare it
  149.   // yourself.  When you find the key you want, you can call
  150.   // thiskey_player() to fill the 'player' structure.
  151.  
  152. #define thiskey_player()    Player.LoadThisKey()  // Use with key_player()
  153.  
  154.  
  155. #endif // End #ifndef __Example4_HEADER_FILE__
  156.  
  157.  
  158. // End of Example4.h
  159.